Skip to content

Conversation

@jyasskin
Copy link
Contributor

@jyasskin jyasskin commented Sep 21, 2025

This is a rough draft of a "define registries" principle, based on the discussion in Hong Kong last week. It will fix #583 once it's polished and merged. I expect it'll need a lot of polishing.


Preview | Diff

Comment on lines +3592 to +3735
Default to defining either
an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]],
but another similar mechanism is also acceptable.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What other mechanism do you think might be appropriate? What criteria do you think apply to the selection of process?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My thought here was that, if we were writing this several years ago I would have put just the IANA process here. When the W3C process arrived, I would have wanted it to be written in such a way that the W3C process were also acceptable. I don't know of another process that would fit now, but there's also no reason that only 2 organizations would be acceptable.

On the other hand, maybe this is an extensibility point for the design principles, and we can just update the design principles instead of defining a registry of registry mechanisms with criteria for adding new ones.

Suggested change
Default to defining either
an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]],
but another similar mechanism is also acceptable.
Default to defining either
an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]].

index.bs Outdated
Comment on lines 3605 to 3747
The definition of the registry must be clear about this interface,
and it should require new entries to include a specification that follows it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The extension point that is governed by a registry needs to be fully-specified. That includes a definition of what to do if an item is not understood (is there a negotiation mechanism? is there feature detection? is the extension ignored when it is not understood? or, does it cause a failure of some sort?)

RFC 6709 goes into some detail about some of the extension models that might apply. Those are for protocols, but the same principles broadly apply to APIs as well.

Then, the requirements for what it takes to define the extension need to be clearly defined, as you say here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've rearranged some things to add this in, and to defer to RFC 6790 for details. How does it look?

index.bs Outdated
Comment on lines 3615 to 3761
Use a permissive registration policy instead of doing this
unless the feature includes
some way to enforce that no implementation can use an unregistered name.
The IETF has found that
when it's too hard to add entries to a registry,
implementers will often simply use names without registering them.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't quite the angle I'd use here. The extent to which you can add tighter constraints varies based on the ecosystem you are deploying into. If your implementers are browsers, then you might imagine that a tighter set of restrictions might be respected and therefore it would be more reasonable to at least try it on.

If you are looking at websites implementing, then you can almost guarantee that registrations won't happen, even if the constraints are very lightweight.

Getting that nuance in might be a good idea.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I replaced the tail of this paragraph with this discussion, and added a paragraph saying (roughly) that if this is likely, then it can justify a FCFS-with-no-spec policy.

index.bs Outdated
Comment on lines 3622 to 3766
When a feature's main specification defines some initial registry entries,
each one can be either required or optional for implementations to recognize.
If implementations need to pick an understood registry entry to send to their recipients,
then the registry should include at least 1 required entry.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extensions for optional features - ones that are simply ignored if not understood - don't need this.

You should say that where the functioning of a specification depends on choosing and using an registered value, then you have three choices:

  • One party implements all the options.
  • You mandate a baseline that all parties implement.
  • Risk interoperability failure if the intersection of options between entities is empty.

And that's for a two-party negotiation. There are many things that the W3C documents where there are more than two potential actors involved.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to incorporate optional features.

I feel like we should only endorse one of your three choices:

  • having 1 party implement all options means that party gets a veto on new options ... maybe it's saying that all values have to be marked as required for one side of the protocol so that the other side can make a free choice ... and in that case, values can only be added in a revision of the main spec, so it's not a registry anymore.
  • the baseline is equivalent to requiring at least 1 entry
  • We shouldn't endorse a plan that leads to interoperability failures.

index.bs Outdated
Comment on lines 3632 to 3780
It can be tempting to use URLs instead of registered strings to identify extensions.
This has the benefit of making it very easy to extend the feature,
by just picking a URL from a domain that the extender controls.
However, there's no way to ensure that
these URLs point to a specification for the extension they name,
or even that the domain stays under the control of the entity that defined the extension.
URLs are appropriate for a few kinds of completely-permissionless extension,
but most of the time a WG-managed permissive registry table will work better.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

XML namespaces use URIs (not URLs). They are not using URIs for their ability to resolve to something; most XML namespace URIs, if they are resolved, point to nothing useful. You seem to imply that they could point to something; some do, but that's never been the goal.

They use URIs because the domain into which they are being deployed does not benefit from centralized coordination. They need identifiers and a way to generate them without coordination or - save us all - namecoin-style consensus. Indeed, it would be a mistake to require centralized coordination for those (doubly so for a wasteful distributed consensus). XML is a file format that is used by many people for many reasons. There is no value in asking people to coordinate identifier allocation. The same applies to JSON-LD, for similar reasons 1.

But the question we need to answer here is different. If you are specifying an extension to a protocol, why would you use a registry rather than letting the proverbial thousand flowers bloom? That all comes down to how you conceive of the interoperability goals of the extension point.

An optional, ignorable extension might benefit from a registry if there is a greater need to have different implementations agree on what the meaning of the extension is. In TLS, we have a registry for extensions, not just because there is a limited space available, but because the goal of defining an extension is to enable a shared understanding of the space.

In comparison, the IPTC metadata format uses URLs, because they don't see a need to constrain the space of options. There, the risk that people define multiple identifiers that are close, or even identical, in meaning is something that is tolerated so that there is a low-coordination way of adding metadata for limited or proprietary uses.

An extension point that determines everything that follows, like TLS ciphersuites or digital credential protocols, benefits more from coordination than something that can be readily ignored. Those are places where mandating implementation of a core by all (or a subset by browsers) is necessary.

Footnotes

  1. Even if you don't think that JSON-LD is solving a problem that matters, this choice is not one that is really in contention, to my mind.

Copy link
Member

@annevk annevk Sep 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

XML namespaces use strings that by convention often look like URLs and might parse as one, if we're going to quibble about details.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After some of the rewrites above, the paragraph about URIs/URLs wound up fitting in as a thing one might do if the alternative is a specification-less registry. They're hierarchical in the IETF sense, but they also tend to risk a DNS entry being bought out from under the original creator. And they're usually more bytes than really necessary, but that's petty and I didn't find a convenient way to work it in.

The IPTC example seems like a case where they should have defined the main terms in the main spec, or possibly done a hierarchical space where each "Recommended/used Prefix" is controlled by a particular entity.

Or are you thinking that we should call out the case of enabling local/proprietary extensions as a time when URLs are actually the right way to go?

index.bs Outdated
Comment on lines 3626 to 3771
If implementations can be
divided into distinct [[spec-variability#subdivision-profile|profiles]]
that tend not to need to communicate with other profiles,
it can be sufficient for each profile to require a registry entry
even if the main specification leaves them all optional.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's not interoperability in the sense that we should care about here.

https://www.w3.org/TR/ethical-web-principles/#oneweb

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to drop this sentence, although DIDs might be an example where there are many specifications (protocols) that have fields in which a DID could appear, and each of those specifications needs to mandate at least 1 DID Method to be implemented, but not all of those specifications need to agree on the same Method. I don't think that would violate the One Web principle, although it also wouldn't be ideal.

jyasskin and others added 2 commits November 2, 2025 19:38
Co-authored-by: Martin Thomson <[email protected]>
* Define "extension point".
* Say to specify the extension point itself.
* Discuss how many registration constraints the ecosystem will accept.
* Deal with "optional" extension points.
* Don't acknowledge multi-profile specs.
* Reframe URI-named extensibility systems.
Copy link
Contributor Author

@jyasskin jyasskin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the long delay. How's it look now?

Comment on lines +3592 to +3735
Default to defining either
an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]],
but another similar mechanism is also acceptable.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My thought here was that, if we were writing this several years ago I would have put just the IANA process here. When the W3C process arrived, I would have wanted it to be written in such a way that the W3C process were also acceptable. I don't know of another process that would fit now, but there's also no reason that only 2 organizations would be acceptable.

On the other hand, maybe this is an extensibility point for the design principles, and we can just update the design principles instead of defining a registry of registry mechanisms with criteria for adding new ones.

Suggested change
Default to defining either
an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]],
but another similar mechanism is also acceptable.
Default to defining either
an IANA registry governed by [[RFC8126]] or a [[w3c-process#registries|W3C Registry]].

index.bs Outdated
Comment on lines 3605 to 3747
The definition of the registry must be clear about this interface,
and it should require new entries to include a specification that follows it.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've rearranged some things to add this in, and to defer to RFC 6790 for details. How does it look?

index.bs Outdated
Comment on lines 3615 to 3761
Use a permissive registration policy instead of doing this
unless the feature includes
some way to enforce that no implementation can use an unregistered name.
The IETF has found that
when it's too hard to add entries to a registry,
implementers will often simply use names without registering them.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I replaced the tail of this paragraph with this discussion, and added a paragraph saying (roughly) that if this is likely, then it can justify a FCFS-with-no-spec policy.

index.bs Outdated
Comment on lines 3626 to 3771
If implementations can be
divided into distinct [[spec-variability#subdivision-profile|profiles]]
that tend not to need to communicate with other profiles,
it can be sufficient for each profile to require a registry entry
even if the main specification leaves them all optional.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm happy to drop this sentence, although DIDs might be an example where there are many specifications (protocols) that have fields in which a DID could appear, and each of those specifications needs to mandate at least 1 DID Method to be implemented, but not all of those specifications need to agree on the same Method. I don't think that would violate the One Web principle, although it also wouldn't be ideal.

index.bs Outdated
Comment on lines 3622 to 3766
When a feature's main specification defines some initial registry entries,
each one can be either required or optional for implementations to recognize.
If implementations need to pick an understood registry entry to send to their recipients,
then the registry should include at least 1 required entry.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to incorporate optional features.

I feel like we should only endorse one of your three choices:

  • having 1 party implement all options means that party gets a veto on new options ... maybe it's saying that all values have to be marked as required for one side of the protocol so that the other side can make a free choice ... and in that case, values can only be added in a revision of the main spec, so it's not a registry anymore.
  • the baseline is equivalent to requiring at least 1 entry
  • We shouldn't endorse a plan that leads to interoperability failures.

index.bs Outdated
Comment on lines 3632 to 3780
It can be tempting to use URLs instead of registered strings to identify extensions.
This has the benefit of making it very easy to extend the feature,
by just picking a URL from a domain that the extender controls.
However, there's no way to ensure that
these URLs point to a specification for the extension they name,
or even that the domain stays under the control of the entity that defined the extension.
URLs are appropriate for a few kinds of completely-permissionless extension,
but most of the time a WG-managed permissive registry table will work better.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After some of the rewrites above, the paragraph about URIs/URLs wound up fitting in as a thing one might do if the alternative is a specification-less registry. They're hierarchical in the IETF sense, but they also tend to risk a DNS entry being bought out from under the original creator. And they're usually more bytes than really necessary, but that's petty and I didn't find a convenient way to work it in.

The IPTC example seems like a case where they should have defined the main terms in the main spec, or possibly done a hierarchical space where each "Recommended/used Prefix" is controlled by a particular entity.

Or are you thinking that we should call out the case of enabling local/proprietary extensions as a time when URLs are actually the right way to go?

Copy link
Contributor

@matatk matatk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great.

Do you think that some concrete examples might help?

In terms of positive examples, there are a few that seem to work well, including: link types/rel attribute values, and Well-known URIs.

But are there any non-contentious, and preferably not recent, examples of where a registry was implemented, but wasn't a good idea, or was decided against?

@jyasskin
Copy link
Contributor Author

jyasskin commented Nov 3, 2025

Examples could help. Some that come to mind:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Guidance on registries?

4 participants